fix(ui): collapse the BibleCard error state into one alert region by cameronapak · Pull Request #321 · youversion/platform-sdk-react

cameronapak · 2026-08-07T17:18:41Z

What problems was I solving

The BibleCard component shows an error state when a Bible passage does not load. This error state had two faults.

Fault 1. A screen reader announced two alerts for one failure.

The card showed two separate regions with role="alert". The first region was the word "ERROR" in the header slot. The second region was an icon plus a sentence that explains the error. Both regions were live regions. A screen reader therefore announced the word "Error" first, and then announced the sentence as a second alert.

Fault 2. An error was a dead end.

The card hid the version picker when passageError was set. A 404 error means the passage is not in the selected Bible version. The fix is to select a different version. The card removed that control at the moment the reader needed it.

After this change, a failed request announces one alert. That alert carries the sentence that explains the error. The reader can also select a different version without leaving the card.

What user-facing changes did I ship

packages/ui/src/components/bible-card.tsx - The word "ERROR" keeps its position and its style. It loses role="alert" and aria-live, so a screen reader no longer announces it as a second alert. The version picker now shows during an error.
packages/ui/src/components/verse.tsx - The message block loses a duplicate aria-live, because role="alert" already makes the block a live region. The icon now has aria-hidden, so a screen reader skips it.

VerseOfTheDay and standalone BibleTextView show the same message block. Both components get the same two accessibility fixes. The text that they show does not change. Neither component gets an "ERROR" label, because that label belongs to the BibleCard header slot.

This change adds no new i18n keys. The eight status-aware messages, their six locales, and the code that derives errors are all unchanged.

How I implemented it

One alert region

In bible-card.tsx, BibleCardHeaderError was a div with role="alert" and aria-live="polite" around one <h2>. It is now the <h2> alone. The div held no classes that changed the layout, so the card looks the same.

The <h2> uses the same classes as BibleCardHeaderReference. This reuse is deliberate. The card already puts an <h2> in that slot for the passage reference. The error label therefore adds no new heading level to the outline of the host page.

In verse.tsx, VerseUnavailableMessage keeps role="alert" and becomes the only alert region. It loses aria-live and marks its icon aria-hidden.

The header ternary keeps three branches instead of two. Two branches would fall through to the loading spinner during an error. The spinner would then turn forever.

The version picker during an error

In bible-card.tsx, the condition changed from showVersionPicker && !passageError to showVersionPicker. This is the whole source change. The picker reads versionNum and not the passage, so it works while passageError is set.

The header row needs no layout change. The word "ERROR" still sits on the left and the picker on the right. The class yv:justify-between is still correct.

Tests and the Storybook story

bible-card.test.tsx gets a new BibleCard - Error state block with five tests:

Exactly one role="alert" region shows.
That region carries the 503 sentence.
The header shows an <h2> that reads "Error".
No role="status" spinner shows during an error.
The version picker shows and is enabled during an error.

The picker test needed five more hook mocks: useLanguages, useLanguage, useVersions, useFilteredVersions, and useOrganizations. The file mocks the hooks package with a bare vi.mock call. Every export therefore returns undefined, and BibleVersionPicker.Root reads these five.

verse.test.tsx gets one test. The alert has no aria-live. The icon has aria-hidden. The alert holds no "Error" text, because a standalone BibleTextView has no header slot.

bible-card.stories.tsx gets showVersionPicker: true on the Error story. Its play function now tests for one alert region and an enabled picker.

.changeset/biblecard-single-error-alert.md is a patch that names @youversion/platform-react-ui.

Deviations from the plan

The plan artifact is a structure outline, not a plan file. It changed twice during the work, so it already describes the final direction. The code and the outline now agree on every phase.

Implemented as planned

VerseUnavailableMessage keeps role="alert", loses aria-live, and marks its icon aria-hidden.
BibleCardHeaderError is now a bare <h2> with the classes of BibleCardHeaderReference.
The header ternary keeps three branches.
The version picker condition loses && !passageError.
The tests and the story cover every case that the outline listed.
No new i18n keys. The errorHeading key comes from the existing locale files.

Deviations and surprises

The outline said that the story must test that the picker shows and is enabled. The story also tests that the button text matches /NIV/i. This test is stricter than the outline, and it does not conflict with it.
The changeset names one package. The outline asked for three. .changeset/config.json already puts the three packages in a fixed group, so a changeset that names platform-react-ui alone still bumps all three. pnpm changeset status shows this result. A changeset that names all three would also copy this UI-only text into packages/core/CHANGELOG.md and packages/hooks/CHANGELOG.md. The three most recent UI fixes on main (b592e72, 9c2e8e4, 9a2b3e9) each name only the package that changed. The outline records this deviation in its Phase 3 section.

Additions that are not in the plan

Doc comments above BibleCardHeaderError, the header ternary, the version picker condition, and VerseUnavailableMessage. They put the reasoning of the outline into the source. They change no behavior.

Items that were planned but not implemented

None.

How the outline changed during the work

The outline changed shape twice. This history matters only if you read the artifacts next to the diff.

The design discussion decided to remove the header label completely.
A later outline revision put the word "Error" back, but inside the message block, above the sentence.
On 2026-08-07, Cam reviewed the result in Storybook and reversed that decision. The label stays in the header slot. Only its alert semantics change. The code does this.

That reversal made two planned Phase 2 changes unnecessary. Both changes assumed an empty header slot. The header slot always has a child during an error. The justify-end change and the empty-row check therefore left the outline before Phase 2 started.

How to verify it

Run these commands first:

git fetch origin ype-2360-react-biblecard-error-state-needs-better-text
git checkout ype-2360-react-biblecard-error-state-needs-better-text
pnpm install
pnpm --filter @youversion/platform-core --filter @youversion/platform-react-hooks build
pnpm --filter @youversion/platform-react-ui storybook

Manual tests

Open Components/BibleCard → Error. Make sure that "ERROR" is in the header slot, above one block with the icon and the sentence.
Set the Storybook theme global to dark. Make sure that the story still reads correctly.
Start VoiceOver. Make sure that it announces one alert, and that this alert is the sentence.
In the Error story, open the version picker and select a different version.
Make sure that the card recovers when the new version returns the passage.
Open Components/VerseOfTheDay and Components/BibleTextView. Both show the icon and the sentence, with no label.

Automated tests

pnpm typecheck
pnpm lint
pnpm test
pnpm --filter @youversion/platform-react-ui test:integration

If you use a fresh worktree, do these two steps before you run the commands above:

Copy packages/core/.env.example to packages/core/.env.local. Without this file, YVP_API_HOST is empty and all 16 core suites fail to collect. The core tests use MSW mocks, so placeholder values are enough. CI supplies both values as secrets.
Run pnpm --filter @youversion/platform-react-ui build:css. Without dist/tailwind.css, two WideContainer stories fail on the missing yv:card-content cap. This failure is not related to this branch.

Results on this branch: pnpm test passes 1065 tests (core 369, hooks 289, ui 407). test:integration passes 452 tests. pnpm build --force passes, including verify:styles.

Description for the changelog

Fix the BibleCard error state that announced two alerts instead of one, and keep the version picker usable during an error.

Greptile Summary

The PR consolidates BibleCard errors into one alert region while preserving an error heading and allowing users to switch Bible versions during passage failures.

Removes duplicate live-region semantics from the card header and shared unavailable-message component.
Keeps the version picker mounted as an in-card recovery path.
Hides the decorative error icon from assistive technology.
Adds unit and Storybook coverage for alert count, heading semantics, and picker availability.
Adds the required patch changeset.

Confidence Score: 5/5

The PR appears safe to merge, with the accessibility and error-recovery behavior consistently implemented and covered.

The card retains one reachable error alert, preserves a semantic error heading, and exposes the existing version picker during passage failures without a supported path to a render, state, or accessibility regression.

Important Files Changed

Filename	Overview
packages/ui/src/components/bible-card.tsx	Separates the visual error heading from the sole body alert and keeps the version picker available during passage errors without introducing a conflicting loading state.
packages/ui/src/components/verse.tsx	Removes redundant live-region configuration and marks the error icon decorative while retaining the shared status-aware alert message.
packages/ui/src/components/bible-card.test.tsx	Adds focused coverage for one alert, the error heading, absence of a loading status, and picker usability during errors.
packages/ui/src/components/verse.test.tsx	Verifies the shared error alert has no redundant aria-live attribute, hides its icon, and does not add an Error label to standalone usage.
packages/ui/src/components/bible-card.stories.tsx	Updates the integration error story to exercise the single-alert contract and available version-picker recovery path.
.changeset/biblecard-single-error-alert.md	Records the user-visible accessibility and recovery behavior as a patch release.

_{Reviews (1): Last reviewed commit: "chore: add changeset for the BibleCard e..." | Re-trigger Greptile}

A failed passage request rendered two competing role="alert" regions: the "ERROR" label in the header slot and the icon plus status-aware sentence in the body. Screen readers announced both. The body block is now the only alert region. The header label keeps its place and its styling but drops role="alert" and aria-live. The body block drops its redundant aria-live and hides its icon with aria-hidden. No new i18n keys, and no change to how errors are derived. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

A 404 means the passage is missing from the selected version, and switching versions is the fix. The picker was hidden whenever passageError was set, so the card offered no way out. The picker reads versionNum rather than the passage, so it renders and works while an error is showing. The header row needs no change: the "ERROR" label still sits on the left and the picker on the right. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

changeset-bot · 2026-08-07T17:18:44Z

🦋 Changeset detected

Latest commit: f7fcc99

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 4 packages

Name	Type
@youversion/platform-react-ui	Patch
vite-react	Patch
@youversion/platform-core	Patch
@youversion/platform-react-hooks	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

bmanquen · 2026-08-10T18:47:04Z

+    await waitFor(async () => {
+      await expect(versionPickerButton).toBeEnabled();
+      await expect(versionPickerButton).toHaveTextContent(/NIV/i);
    });


Should we assert that changing the version clears the error in this test?

bmanquen · 2026-08-10T18:49:26Z

+    expect(picker).toBeInTheDocument();
+    expect(picker).toBeEnabled();
+    expect(picker).toHaveTextContent('BSB');
+  });


Should we assert that a successful version change clears the error in this test or create another separate test to assert this?

bmanquen

Review of this branch against the repo's documented standards and against what the PR body says it ships. Four inline comments below; two of them I'd call blocking.

Blocking

The aria-live removal in verse.tsx is a politeness change, not a de-duplication — it takes VerseOfTheDay and standalone BibleTextView from polite to assertive. The PR body and the changeset both call it "redundant"/"duplicate", and the source comment added in the same hunk says the opposite.
Turning on showVersionPicker in the Error story makes an integration-tagged story fire unmocked network requests.

Non-blocking
3. The changeset text needs the same correction as (1).
4. createError is duplicated verbatim across the two test files, and the new jsdom tests re-assert what the Error play function already covers — packages/ui/AGENTS.md prefers Storybook for UI component tests.

Separately, a scoping question, not a code finding. YPE-2360 is titled "React BibleCard error state needs better text", and this branch changes zero user-visible strings — packages/ui/src/lib/bible-text-error.ts and all six locale files are untouched. The PR body confirms this ("The text that they show does not change"), but doesn't record it as a deviation. Alert semantics and picker availability are both real fixes; if the wording work was deliberately split off, worth saying so here so the ticket doesn't look closed by this PR.

Everything the PR body claims about the implementation checks out otherwise: exactly one role="alert" renders during an error, the header ternary really does keep three branches, the picker renders and stays enabled while passageError is set, no new i18n keys, and changeset status confirms the single-package changeset bumps all three via the fixed group.

bmanquen · 2026-08-10T19:21:20Z

 function VerseUnavailableMessage({ message }: { message: string }): React.ReactElement {
  return (
    <div
      role="alert"


Removing aria-live="polite" here isn't a de-duplication — it's a politeness change.

role="alert" implies aria-live="assertive". The explicit aria-live="polite" was overriding that implicit value down to polite, so deleting it doesn't leave the behavior unchanged — it restores assertive, and the message now interrupts whatever the screen reader is currently speaking.

The doc comment added in this same hunk actually states this correctly ("role="alert" already implies an assertive live region"), which is what makes the "duplicate"/"redundant" framing in the PR body and changeset inconsistent with the code.

This lands on VerseOfTheDay and standalone BibleTextView too, where the PR promises only that "the text that they show does not change" — the announcement urgency does change for both.

If assertive is the intent, that's defensible for a failed load, but it should be stated as the deliberate change it is. If it isn't intended, keep aria-live="polite" — it still wins over the implicit assertive.

bmanquen · 2026-08-10T19:21:20Z

  args: {
    reference: 'LUK.1.39-45',
    versionId: 111,
+    showVersionPicker: true,


This makes an integration-tagged story hit the real API.

showVersionPicker: true mounts BibleVersionPicker.Root, which calls useLanguages and useVersions unconditionally in the component body (bible-version-picker.tsx:311, :316, :317) — not lazily when the popover opens. This story's msw handlers only cover */v1/bibles/111 and the passage, and .storybook/preview.tsx:28 sets onUnhandledRequest: 'warn', so the language and version-list requests fall through to the live host instead of failing loudly.

Adding handlers for the languages/versions endpoints fixes this and has a second benefit: it makes the manual verification step in the PR description ("open the version picker and select a different version… make sure the card recovers") actually reproducible from this story, which it currently isn't.

bmanquen · 2026-08-10T19:21:20Z

+
+Fix the `BibleCard` error state announcing two alerts, and keep the version picker usable while an error is showing. The "Error" label stays in the header slot but drops its `role="alert"` and `aria-live`, leaving the message block in the card body as the only alert region. The picker no longer disappears on error, so a 404 has an in-card fix: switch to a version that carries the passage.
+
+The shared message block also drops a redundant `aria-live` and hides its icon with `aria-hidden`, so `VerseOfTheDay` and standalone `BibleTextView` pick up the same accessibility fixes. Their visible text is unchanged, and neither gains an "Error" label. The eight status-aware messages, their six locales, and how errors are derived are untouched.


"drops a redundant aria-live" — same correction as the verse.tsx comment: it wasn't redundant, it was an override, and removing it moves VerseOfTheDay and standalone BibleTextView from polite to assertive announcements.

docs/review-guidelines.md asks whether the code actually implements what the PR description claims, and whether consumer-visible changes are identified in the changeset. Since this ships to consumers of both those components, the changeset should say the announcement becomes assertive rather than describing it as a no-op cleanup.

bmanquen · 2026-08-10T19:21:20Z

 });

+describe('BibleCard - Error state', () => {
+  function createError(message: string, status?: number): Error {


Two smaller things on the new test block:

createError is byte-identical to the one added in verse.test.tsx:888. Worth pulling into a shared test helper rather than keeping two copies in sync.

These five jsdom tests largely restate the updated Error play function (one alert, the message text, the picker enabled). packages/ui/AGENTS.md → TESTING says to prefer Storybook with play for UI component tests. The picker test in particular hand-mocks five hooks (useLanguages, useLanguage, useVersions, useFilteredVersions, useOrganizations) that are BibleVersionPicker's internals — so it breaks whenever that component's data dependencies change, which is exactly the coupling the Storybook preference avoids.

cameronapak and others added 3 commits August 7, 2026 12:03

chore: add changeset for the BibleCard error state fix

f7fcc99

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

cameronapak requested review from bmanquen and camrun91 August 10, 2026 17:04

cameronapak self-assigned this Aug 10, 2026

bmanquen reviewed Aug 10, 2026

View reviewed changes

Navigation Menu

Uh oh!

fix(ui): collapse the BibleCard error state into one alert region - #321

fix(ui): collapse the BibleCard error state into one alert region#321
cameronapak wants to merge 3 commits into
mainfrom
ype-2360-react-biblecard-error-state-needs-better-text

cameronapak commented Aug 7, 2026 •

edited

Loading

Uh oh!

changeset-bot Bot commented Aug 7, 2026

Uh oh!

bmanquen Aug 10, 2026

Uh oh!

bmanquen Aug 10, 2026

Uh oh!

bmanquen left a comment

Uh oh!

bmanquen Aug 10, 2026

Uh oh!

bmanquen Aug 10, 2026

Uh oh!

bmanquen Aug 10, 2026

Uh oh!

bmanquen Aug 10, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants


		Fix the `BibleCard` error state announcing two alerts, and keep the version picker usable while an error is showing. The "Error" label stays in the header slot but drops its `role="alert"` and `aria-live`, leaving the message block in the card body as the only alert region. The picker no longer disappears on error, so a 404 has an in-card fix: switch to a version that carries the passage.

		The shared message block also drops a redundant `aria-live` and hides its icon with `aria-hidden`, so `VerseOfTheDay` and standalone `BibleTextView` pick up the same accessibility fixes. Their visible text is unchanged, and neither gains an "Error" label. The eight status-aware messages, their six locales, and how errors are derived are untouched.

Uh oh!

Conversation

cameronapak commented Aug 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What problems was I solving

What user-facing changes did I ship

How I implemented it

One alert region

The version picker during an error

Tests and the Storybook story

Deviations from the plan

Implemented as planned

Deviations and surprises

Additions that are not in the plan

Items that were planned but not implemented

How the outline changed during the work

How to verify it

Manual tests

Automated tests

Description for the changelog

Greptile Summary

Confidence Score: 5/5

Important Files Changed

Uh oh!

changeset-bot Bot commented Aug 7, 2026

🦋 Changeset detected

Uh oh!

bmanquen Aug 10, 2026

Choose a reason for hiding this comment

Uh oh!

bmanquen Aug 10, 2026

Choose a reason for hiding this comment

Uh oh!

bmanquen left a comment

Choose a reason for hiding this comment

Uh oh!

bmanquen Aug 10, 2026

Choose a reason for hiding this comment

Uh oh!

bmanquen Aug 10, 2026

Choose a reason for hiding this comment

Uh oh!

bmanquen Aug 10, 2026

Choose a reason for hiding this comment

Uh oh!

bmanquen Aug 10, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

cameronapak commented Aug 7, 2026 •

edited

Loading